home *** CD-ROM | disk | FTP | other *** search
/ NeXTSTEP 3.3 (Developer)…68k, x86, SPARC, PA-RISC] / NeXTSTEP 3.3 Dev Intel.iso / usr / sybase / doc / dbresults.man < prev    next >
Text File  |  1993-04-22  |  6KB  |  155 lines
  1.  
  2.   1                       Version 4.0 -- 5/1/89                dbresults
  3.   ______________________________________________________________________
  4.  
  5.   NAME:  dbresults
  6.  
  7.   FUNCTION:
  8.        Set up the results of the next query.
  9.  
  10.   SYNTAX:
  11.        RETCODE dbresults(dbproc)
  12.  
  13.        DBPROCESS *dbproc;
  14.  
  15.   COMMENTS:
  16.  
  17.        o This routine sets up the next command in the command batch  for
  18.  
  19.  
  20.  
  21.  
  22.  
  23.  
  24.   dbresults               Version 4.0 -- 5/1/89                        2
  25.   ______________________________________________________________________
  26.          processing.  The application program calls it after dbsqlexec()
  27.          or  dbsqlok()  returns  SUCCEED.  The first call to dbresults()
  28.          will always return either SUCCEED  or  NO_MORE_RESULTS  if  the
  29.          call  to  dbsqlexec()  or dbsqlok() has returned SUCCEED.  Once
  30.          dbresults()  returns   SUCCEED,   the   application   typically
  31.          processes any result rows with dbnextrow().
  32.  
  33.        o To manage multiple  input  data  streams  efficiently,  a  UNIX
  34.          application can confirm that unread bytes are available, either
  35.          in the DB-Library network buffer (by calling  DBRBUF())  or  in
  36.          the  network  itself  (by  calling the UNIX select() function),
  37.          before calling dbresults().
  38.        o dbresults() must be called for  each  command  in  the  command
  39.          batch,  whether  or  not  the command returns any rows.  If the
  40.          application code doesn't know how  many  commands  are  in  the
  41.          batch  (for  example, if the application is designed to process
  42.          ad hoc queries), it  can  call  dbresults()  until  it  returns
  43.  
  44.  
  45.  
  46.   3                       Version 4.0 -- 5/1/89                dbresults
  47.   ______________________________________________________________________
  48.          NO_MORE_RESULTS.
  49.  
  50.          dbresults() must also ordinarily be called once for any  stored
  51.          procedure  executed  in  the  command  batch.   However, if the
  52.          stored procedure contains more than one SQL  SELECT  statement,
  53.          then  dbresults()  must be called once for each SELECT.  Again,
  54.          the easiest way to do this is to continue to  call  dbresults()
  55.          until it returns NO_MORE_RESULTS.
  56.        o To cancel the remaining results from  the  command  batch  (and
  57.          eliminate  the  need  to  continue calling dbresults() until it
  58.          returns NO_MORE_RESULTS), call dbcancel().
  59.  
  60.        o To determine whether a particular command is one  that  returns
  61.          rows  and  needs  results  processing  with  dbnextrow(),  call
  62.          DBROWS() after the dbresults() call.
  63.        o The typical  sequence  of  calls  for  using  dbresults()  with
  64.          dbsqlexec() is:
  65.  
  66.  
  67.  
  68.   dbresults               Version 4.0 -- 5/1/89                        4
  69.   ______________________________________________________________________
  70.          DBINT        xvariable;
  71.          DBCHAR       yvariable[10];
  72.  
  73.          /* read the query into the command buffer */
  74.          dbcmd(dbproc, "select x = 100, y = 'hello'");
  75.  
  76.          /* send the query to SQL Server */
  77.          dbsqlexec(dbproc);
  78.  
  79.          /* get ready to process the results of the query */
  80.          dbresults(dbproc);
  81.  
  82.          /* bind column data to program variables */
  83.          dbbind(dbproc, 1, INTBIND, (DBINT) 0, (BYTE *) &xvariable);
  84.          dbbind(dbproc, 2, STRINGBIND, (DBINT) 0, yvariable);
  85.  
  86.          /* now process each row */
  87.  
  88.  
  89.  
  90.   5                       Version 4.0 -- 5/1/89                dbresults
  91.   ______________________________________________________________________
  92.          while (dbnextrow(dbproc) != NO_MORE_ROWS)
  93.          {
  94.              C-code to print or process row data
  95.          }
  96.  
  97.          Example 1 in the DB-Library Reference Supplement shows  how  to
  98.          use dbresults() to process a multi-query command batch.
  99.  
  100.        o Another use for dbresults() is to  process  the  results  of  a
  101.          remote   procedure   call   made  with  dbrpcsend().   See  the
  102.          dbrpcsend() manual page for details.
  103.  
  104.  
  105.  
  106.   PARAMETERS:
  107.        dbproc -  A pointer to the DBPROCESS structure that provides  the
  108.            connection for a particular front-end/SQL Server process.  It
  109.  
  110.  
  111.  
  112.   dbresults               Version 4.0 -- 5/1/89                        6
  113.   ______________________________________________________________________
  114.            contains all the information that DB-Library uses  to  manage
  115.            communications and data between the front end and SQL Server.
  116.  
  117.   RETURNS:
  118.        SUCCEED,   FAIL   or   NO_MORE_RESULTS.    dbresults()    returns
  119.        NO_MORE_RESULTS  if  all commands in the buffer have already been
  120.        processed.  The most common reason  for  failing  is  a  run-time
  121.        error, such as a database permission violation.
  122.  
  123.        The number of commands in the command buffer  determines  whether
  124.        dbsqlexec()  or dbresults() traps a run-time error. If the buffer
  125.        contains only a single  command,  a  run-time  error  will  cause
  126.        dbsqlexec()  to  fail.   If  the command buffer contains multiple
  127.        commands, a run-time error will not cause  dbsqlexec()  to  fail.
  128.        Instead,  the dbresults() call that processes the command causing
  129.        the run-time error will fail.
  130.        The situation is a bit more complicated for run-time  errors  and
  131.  
  132.  
  133.  
  134.   7                       Version 4.0 -- 5/1/89                dbresults
  135.   ______________________________________________________________________
  136.        stored procedures.  A run-time error on an  EXECUTE  command  may
  137.        cause  dbresults()  to fail, in accordance with the rule given in
  138.        the previous paragraph.  A run-time error on a statement inside a
  139.        stored  procedure  will  not  cause dbresults() to fail, however.
  140.        For example, if the stored procedure contains an INSERT statement
  141.        and  the  user  does  not  have insert permission on the database
  142.        table, the INSERT statement will fail, but dbresults() will still
  143.        return  SUCCEED.  To check for run-time errors inside stored pro-
  144.        cedures, use the dbretstatus() routine to look at the procedure's
  145.        return  status, and trap relevant SQL Server messages inside your
  146.        message handler.
  147.  
  148.   SEE ALSO:
  149.        dbbind, dbcancel, dbnextrow,  DBRBUF,  dbresults_a,  dbretstatus,
  150.        DBROWS, dbrpcsend, dbsqlexec, dbsqlok
  151.  
  152.  
  153.  
  154.  
  155.